Create OC Essential Service from Lead with IP Group

The Create OC Essential Service from Lead with IP Group request enables you to create a new service from lead with an IP Group used to create a SIP connection between the customer tenant service and the Online PSTN gateway. Two new IP Groups are created on the SBC device that is configured to connect calls between the PSTN trunk and Microsoft Teams, one for the SIP leg (<IP_Group_Name-c) and another for the Teams leg (<IP_Group_Name-t). On Live Platform , a single IP Group representing the SIP leg is created serving as the SIP Connection between the customer tenant service and the Online PSTN gateway.

IP Groups are mandatory for SIP Registration.

By default, Operator Connect is configured to work with Microsoft Operator Connect 'peering' mode with two IP groups, one for the Microsoft Teams connection and the other for the SIP Trunk connection. The default Operator Connect Onboarding script creates a default Proxy Set 'Teams-OC ' and default IP Group 'Teams-OC' for this purpose .

Using this request, two new IP Groups are created on the SBC device for the service, one for the SIP leg (<IP_Group_Name-c) and another for the Teams leg (<IP_Group_Name-t). On the Live Platform portal, a single IP Group is created serving as the SIP Connection between the customer tenant service and the Online PSTN gateway.

Prior to running this script, you need to run the following requests to obtain data that must be configured in the Request Body:

■

Onboarding scripts (see Managing Script Templates

■

If you are you intercepting Microsoft Teams calls then you must provide the credentials of the Teams App Registration on the customer Azure tenant portal (Application (Client) ID and Client secret)

■

Channel Ids if you wish to attach the new service to a channel (see Get List of Channels)

URI

Copy

{{baseUrl}}/api/v3/customer

HTTP Method

POST

Request Body

Parameter

Type

Description

ConfigurationName

string

■

OcEssential_IPGROUP_TYPE

CustomerShortName

string

Customer short name with the following validation rules:

■

Length between 3 and 15 characters

■

No spaces

■

Include only literal and numerical characters and underscores

CustomerFulName

string

Generally the company name, however, any value can be used.

siteLocation

dictionary:

■

siteLocationName: string

■

sbcId: integer

■

sbcOnboardingScript: integer

■

sbcCleanupScript: integer

■

sbcOcUploadNumberScript: integer

■

sbcOcReleaseNumberScript: integer

The configured SBC used to manage calls for the SIP connection.

■

siteLocationName: The name of the primary SIP connection for this service.

■

sbcId: The SBC Id in the SBC List in the Live Platform database (see Get SBC Devices).

■

sbcOnboardingScript: The SBC Onboarding script number in the Live Platform database (see Get Script Templates).

■

sbcCleanupScript: The matching script number in the Live Platform database for Cleanup of the Onboarding script (see Get Script Templates).

■

sbcOcUploadNumberScript: The script number in the Live Platform database for uploading numbers to the Operator Connect service (see Get Script Templates).

■

sbcOcReleaseNumberScript: The matching script number in the Live Platform database to release numbers from the Operator Connect service (see Get Script Templates).

ovocCustomerType

One of the following values:

■

IPGROUP_TYPE string

■

TENANT_TYPE string

■

IP Group: An IP Group is created for each new customer based on the Customer Shortname. This type is used for the Access Trunk Direct Routing (used for Direct Routing customers when SIP Registration is required).

■

Tenant ID:-The new customer is created based on the Tenant's Azure ID

channelId

string

Id of the channel to attach to the service.

lcCustomerId

string

The Id of the Customer entity in the Operation Center portal. When you specify this value, the new service is created under this entity in the Live Platform topology tree. See Get LC Customers to retrieve this value.

If not specified, separate entities are created for both customer and service in the Live Platform portal, under the Service Provider tenant root folder with the same shortName.

msTenantId

string

Microsoft subscription Tenant ID of the Customer lead.

leadId

string

The Id generated for the lead (see Get All OC Leads).

invitationEmail

string

Email of the customer tenant Global Admin or Service account operator used for Onboarding and securing the connection to the customer M365 platform.

licenseType

integer

OC Essential: 3

licensedUsersCount

integer

The number of user licenses to allocate for the service.

umpCustomerGuid

string($uuid)

CustomerGuid created for the customer tenant when Live Platform OC license is applied.

■

If this field has a value: The Guid of customer created by the Live Platform for the OC lead with the given msTenantid. This value is equivalent to the Id value extracted using Get Services Brief Details (V3).

■

If this field is null: An OC license has not yet been applied to the customer lead.

teamsQos

■

applicationID string

■

applicationPassword string

Credentials of the Application Registration on the customer tenant to connect to the Microsoft Teams Notification Service for retrieving Microsoft Teams calls made by M365 tenant users. This registration must be added to the customer tenant (see Managing Teams Devices).

applicationID

string

The Application (Client) Id of the Application Registration for connecting to the Microsoft Teams Notification Service for retrieving Microsoft Teams calls made by M365 tenant users.

applicationPassword

string

The Client Secret of the Microsoft Teams Notification Service for retrieving Microsoft Teams calls made by M365 tenant users.

scriptParameters refers to:

CustomVar.Variable<VariableSequenceNumber>

dictionary

where <VariableSequenceNumber> is the sequence in database that the variable is defined in the 'Customer variables' column for the script properties (see Customer Variables).

For example, when the following IP-PBX variables are defined in the database in the order: IPPBX-ProxyAddress, IPPBX-ProxyAddress-SIPPort, SIP-HostName then Custom variables should be defined as follows:

■

CustomVar.Variable1: <: IPPBX-ProxyAddress>

■

CustomVar.Variable2: < IPPBX-ProxyAddress-SIPPort>

■

CustomVar.Variable3: <SIP-HostName>

Custom variables can be defined to update specific parameters on the SBC device. These variables must be predefined in the UMP-365 database (see Customer Variables). Also verify that the custom variables notation has been added to the script (see parameter 'sbcOnboardingScript' above) that you are applying to the request.

■

additionalProp1: Custom Script variable argument. For example "CacProfile": "5 sessions"

■

additionalProp2: Custom Script argument. For example, ProxySet": "SIPTrunk",

■

additionalProp3: Custom Script argument. For example, "OnlinePstnGateway": "sandbox1.audiocodes.be"

There are three fields displayed in the schema additionalProp1-3, however there is no limitation for the number of variables that can be added.

webhooks

dictionary:

■

invitationIsPending- string

■

customerCreated- string

■

didChange- string

Webhooks push notification details (see Trigger Notification Email for New Leads). The dictionary includes the following:

■

invitationIsPending: Indicates that the Customer Invitation is pending for completion of the Invitation wizard process to secure connection with the customer M365 platform either through Delegated Token or Application Registration connection.

■

customerCreated: Indicates that the connection to the customer platform has been successfully secured and the service has been successfully created.

■

didChange: Indicates that a number has been uploaded or released for a service.

CallingProfileConfigurationTemplateId

integer

The Id of the Calling Profile Template record that is attached to the tenant service. Calling Profile Provisioning templates allow you to apply Calling Profile Templates when applying license (see Create OC Essential Service from Lead with IP Group), adding OC SIP Connections (see Add SIP Connections), uploading numbers (see Upload Operator Connect Numbers to Customer) and releasing numbers (see Release Operator Connect Numbers from Customer). You can then assign each Calling Profile Provisioning template to a different IP Group. For instance, you might want to configure an IP Group with enhanced security settings based on the site location's topology requirements and map it to a Calling Profile tailored for a specific carrier.

●

This value is assigned to services with IP Group-based SIP Connections.

●

This value cannot be extracted using the API, instead extract it from the Multitenant Web interface.

Example Request Body

Copy


{
  "configurationName": "OcEssential_IPGROUP_TYPE",
  "msTenantId": "f9f53ee0-56e1-43f6-8fe3-5fb322986657",
  "customerShortName": "Bradx35340067",
  "customerFullName": "Bradx35340067",
  "scriptParameters": {
    "ProxySet": "SIPTrunk",
    "OnlinePstnGateway":"oc1.sandbox2.audiocodes.be"}

}

Example Response

The initial response displays the Task Id.

Parameter	Type	Description
Task Id	string	The queued task Id that is generated for this action. You must run the Task request to retrieve the status of the action. See Task Status. Note that the wst string in the prefix is unique for this endpoint.

Parameter

Type

Description

Task Id

string

The queued task Id that is generated for this action. You must run the Task request to retrieve the status of the action. See Task Status. Note that the wst string in the prefix is unique for this endpoint.

Copy

{
"jobId": "wst_80b54f45-6643-4fdf-960a-638c18edb787"
}

The execution of the request may take a few minutes. The status will progress from 'In Progress' to 'Completed Success'.

Copy

{
    "id": "wst_80b54f45-6643-4fdf-960a-638c18edb787",
    "status": "CompletedSuccess",
    "details": [
        "Converted"
    ],
    "executionMessages": [
        {
            "level": "Information",
            "message": "SBC sbc-onboarding done for site Bradx35340067."
        },
        {
            "level": "Information",
            "message": "Site created in Ovoc"
        }
    ],
    "outputData": {}
}

Response Codes

■

200 OK

Parameter

Type

Description

string

Task Id

status

string

One of the following values:

■

In Progress

■

Completed Success

■

Completed Failed

details

string

One of the following values:

■

Converted

executionMessages

list array

List array including the following parameters:

■

level

■

message

level

string

One of the following values:

■

Information

■

Error

message

string

■

The following messages are displayed if the customer is created successfully (displayed in the output of the Get Task Id request):

Copy

 "message": "Site created in Ovoc"

Copy

"message": "SBC sbc-onboarding done for site Bradx35340067."

■

The following Request body includes a customer name with more than 15 characters.

Copy

{
  "configurationName": "OcEssential_IPGROUP_TYPE",
  "msTenantId": "7463427b-8c95-45b4-90ec-7710da369c32",
  "customerShortName": "BradEurope4497123456",
  "customerFullName": "BradEurope44972123456",
  "scriptParameters": {
    "ProxySet": "SIPTrunk",
    "OnlinePstnGateway":"oc1.sandbox2.audiocodes.be"}

}

✔

As a result, the following error is displayed in the output of the Get Task Id request):

Copy

{
    "id": "wst_df298001-41b3-495a-804b-aebecb028723",
    "status": "CompletedFailed",
    "details": [
        "Failed"
    ],
    "executionMessages": [
        {
            "level": "Error",
            "message": "'Customer Short Name' must be between 3 and 15 characters."
        }
    ],
    "outputData": {}
}

■

The following Request body includes an invalid character ".":

Copy

 {
  "configurationName": "OcEssential_IPGROUP_TYPE",
  "msTenantId": "7463427b-8c95-45b4-90ec-7710da369c32",
  "customerShortName": "BradEurope.4497",
  "customerFullName": "BradEurope4497",
  "scriptParameters": {
    "ProxySet": "SIPTrunk",
    "OnlinePstnGateway":"oc1.sandbox2.audiocodes.be"}

}

✔

As a result, the following error is displayed in the output of the Get Task Id request:

Copy

{
    "id": "wst_7accb116-e200-4008-b97d-345cea3250df",
    "status": "CompletedFailed",
    "details": [
        "Failed"
    ],
    "executionMessages": [
        {
            "level": "Error",
            "message": "Customer Short Name contains invalid characters. Allowed characters: letters, numbers and '_'."
        },
        {
            "level": "Error",
            "message": "Customer Full Name contains invalid characters. Allowed characters: letters, numbers, _, ' and space."
        }
    ],
    "outputData": {}
}

umpCustomerGuid

string($uuid)

CustomerGuid created for the customer tenant. This value is equivalent to the Id value extracted using Get Services Brief Details (V3).

If this field is null: An OC license has not yet been applied to the customer lead.

outputData

list array

Additional information.

■

400 Bad Request

Copy

{
    "type": "https://httpstatuses.com/500",
    "title": "Internal Server Error",
    "status": 500,
    "traceId": "00-5bcfb1f75627574e43998a4558b34f5e-85a4aabfabc87feb-00"
}

■

403 Forbidden:

Parameter	Type	Description/Examples
errors	string	Text description of the error.
type	string	"https://tools.ietf.org/html/rfc7231#section-6.5.1"
title	string	Email title. For example "One or more validation errors occurred."
status	error code	HTML error code i.e. 400
detail	string	Additional error details.
traceId	string	Error trace Id
instance	string	Error instance
errorTicket	string	This field may not appear for all return codes.
errorCode	string	This field may not appear for all return codes.
additionalProp1	string	Custom Script variable argument. For example "CacProfile": "5 sessions"
additionalProp2	string	Custom Script argument. For example, ProxySet": "SIPTrunk"
additionalProp3	string	Custom Script argument. For example, "OnlinePstnGateway": "sandbox1.audiocodes.be"

■

404 Not Found

The following example shows an 404 error for lead that is not valid.

Copy

"Invalild lead"

Parameter	Type	Description/Examples
errors	string	Text description of the error.
type	string	"https://tools.ietf.org/html/rfc7231#section-6.5.1"
title	string	Email title. For example "One or more validation errors occurred."
status	error code	HTML error code i.e. 400
detail	string	Additional error details.
traceId	string	Error trace Id
instance	string	Error instance
errorTicket	string	This field may not appear for all return codes.
errorCode	string	This field may not appear for all return codes.
additionalProp1	string	Custom Script variable argument. For example "CacProfile": "5 sessions"
additionalProp2	string	Custom Script argument. For example, ProxySet": "SIPTrunk"
additionalProp3	string	Custom Script argument. For example, "OnlinePstnGateway": "sandbox1.audiocodes.be"

■

409 Conflict

Parameter	Type	Description/Examples
errors	string	Text description of the error.
type	string	"https://tools.ietf.org/html/rfc7231#section-6.5.1"
title	string	Email title. For example "One or more validation errors occurred."
status	error code	HTML error code i.e. 400
detail	string	Additional error details.
traceId	string	Error trace Id
instance	string	Error instance
errorTicket	string	This field may not appear for all return codes.
errorCode	string	This field may not appear for all return codes.
additionalProp1	string	Custom Script variable argument. For example "CacProfile": "5 sessions"
additionalProp2	string	Custom Script argument. For example, ProxySet": "SIPTrunk"
additionalProp3	string	Custom Script argument. For example, "OnlinePstnGateway": "sandbox1.audiocodes.be"

■

500 Internal Server Error

Copy

{
    "type": "https://httpstatuses.com/500",
    "title": "Internal Server Error",
    "status": 500,
    "traceId": "00-5bcfb1f75627574e43998a4558b34f5e-85a4aabfabc87feb-00"
}